/* Copyright 2009
 *
 * This program and the accompanying materials
 * are made available under the terms of the
 * Eclipse Public License v1.0 which accompanies
 * this distribution, and is available at
 *
 * 		http://www.eclipse.org/legal/epl-v10.html
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
 * OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * Contributors:
 * 	   IBM Corporation - initial API and implementation for JDT/DLTK
 *     Sean W. Quinn - initial adoption for use with PHP from various sources.
 */
package org.eclipse.php.core;

import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.jobs.ISchedulingRule;
import org.eclipse.dltk.core.IBuildpathAttribute;
import org.eclipse.dltk.core.IModelElement;

/**
 * Common protocol for all elements provided by the PHP model. PHP model
 * elements are exposed to clients as handles to the actual underlying element.
 * The PHP model may hand out any number of handles for each element. Handles
 * that refer to the same element are guaranteed to be equal, but not
 * necessarily identical.
 * <p>
 * Methods annotated as "handle-only" do not require underlying elements to
 * exist. Methods that require underlying elements to exist throw a
 * <code>PHPModelException</code> when an underlying element is missing.
 * <code>PHPModelException.isDoesNotExist</code> can be used to recognize this
 * common special case.
 * </p>
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
@SuppressWarnings("restriction")
public interface IPHPElement extends IAdaptable, IModelElement {


	/**
	 * Constant representing a class file. A PHP element with this type can be
	 * safely cast to {@link IScriptFile}.
	 */
	int SCRIPT_FILE = 20;

	/**
	 * Constant representing a PHP model (workspace level object). A PHP element
	 * with this type can be safely cast to {@link IPHPModel}.
	 */
	int PHP_MODEL = 21;

	/**
	 * Constant representing a PHP project. A PHP element with this type can be
	 * safely cast to {@link IPHPProject}.
	 */
	int PHP_PROJECT = 22;

	/**
	 * Constant representing a package fragment root. A PHP element with this
	 * type can be safely cast to {@link INamespaceFragmentRoot}.
	 */
	int NAMESPACE_FRAGMENT_ROOT = 23;

	/**
	 * Constant representing a package fragment. A PHP element with this type
	 * can be safely cast to {@link INamespaceFragment}.
	 */
	int NAMESPACE_FRAGMENT = 24;

	/**
	 * Constant representing a package declaration within a compilation unit. A
	 * PHP element with this type can be safely cast to
	 * {@link INamespaceDeclaration}.
	 */
	int NAMESPACE_DECLARATION = 25;

	/**
	 * Constant representing all import declarations within a compilation unit.
	 * A PHP element with this type can be safely cast to
	 * {@link IUseContainer}.
	 */
	int USE_CONTAINER = 26;

	/**
	 * Constant representing an import declaration within a compilation unit. A
	 * PHP element with this type can be safely cast to {@link IUseDeclaration}.
	 */
	int USE_DECLARATION = 27;

	/**
	 * Constant representing a local variable declaration. A PHP element with
	 * this type can be safely cast to {@link ILocalVariable}.
	 */
	int LOCAL_VARIABLE = 28;

	/**
	 * Constant representing a Java compilation unit.
	 * A Java element with this type can be safely cast to {@link IProgramUnit}.
	 */
	int PROGRAM_UNIT = 29;

	/**
	 * <p>
	 * Returns the PHPdoc as an html source if this element has an attached
	 * javadoc, null otherwise.
	 * </p>
	 * <p>
	 * This should be used only for binary elements. Source elements will always
	 * return null.
	 * </p>
	 * <p>
	 * The encoding used to read the javadoc is the one defined by the content
	 * type of the file. If none is defined, then the project's encoding of this
	 * java element is used. If the project's encoding cannot be retrieved, then
	 * the platform encoding is used.
	 * </p>
	 * <p>
	 * In case of the javadoc doesn't exist for this element, null is returned.
	 * </p>
	 *
	 * <p>
	 * The html is extracted from the attached javadoc and provided as is. No
	 * transformation or validation is done.
	 * </p>
	 *
	 * @param monitor
	 *            the given progress monitor
	 * @exception PHPModelException
	 *                if:
	 *                <ul>
	 *                <li>this element does not exist</li>
	 *                <li>retrieving the attached javadoc fails (timed-out,
	 *                invalid URL, ...)</li>
	 *                <li>the format of the javadoc doesn't match expected
	 *                standards (different anchors,...)</li>
	 *                </ul>
	 * @return the extracted javadoc from the attached javadoc, null if none
	 * @see IBuildpathAttribute#JAVADOC_LOCATION_ATTRIBUTE_NAME
	 * @since 3.2
	 */
	String getAttachedPHPdoc(IProgressMonitor monitor) throws PHPModelException;

	/**
	 * Returns a string representation of this element handle. The format of the
	 * string is not specified; however, the identifier is stable across
	 * workspace sessions, and can be used to recreate this handle via the
	 * <code>PHPCore.create(String)</code> method.
	 *
	 * @return the string handle identifier
	 * @see PHPCore#create(java.lang.String)
	 */
	String getHandleIdentifier();

	/**
	 * Returns the PHP model. This is a handle-only method.
	 *
	 * @return the PHP model
	 */
	IPHPModel getPHPModel();

	/**
	 * Returns the PHP project this element is contained in, or
	 * <code>null</code> if this element is not contained in any PHP project
	 * (for instance, the <code>IPHPModel</code> is not contained in any PHP
	 * project). This is a handle-only method.
	 *
	 * @return the containing PHP project, or <code>null</code> if this element
	 *         is not contained in a PHP project
	 */
	IPHPProject getPHPProject();

	/**
	 * Returns the scheduling rule associated with this PHP element. This is a
	 * handle-only method.
	 *
	 * @return the scheduling rule associated with this PHP element
	 * @since 3.0
	 */
	ISchedulingRule getSchedulingRule();
}
